01 · Instruction Tool · what is it?

The Instruction Tool

An extra tool that can be added to MCP Deployments or Gateways to provide the information and instruction an agent needs to use the other tools inside well. It's written by you and your team, and it carries the info a generic tool definition never could: your team's conventions for writing Jira tickets, how to navigate your Confluence spaces, which Grafana datasources correspond to what. With the Instruction Tool, Gateways and Deployments become tailored to your team.

Tool schemas tell an agent what it can call. The Instruction Tool tells it how to actually use the surface well.

02 · The problem

Agents can get led astray… without hallucinating

Here's a real world example. A user is talking to an LLM that has a Grafana MCP attached. They want to know if there are any errors in their production environments. The agent has access to all the right data, and it reasons carefully with what it can see. But one fact lives only in your team's heads, and the same request can play out three very different ways.

One example · Grafana datasources

“Pull authentication errors in prod from the past hour from Grafana.”

Without Airia's Instruction Tool

With Airia's Instruction Tool

Path A · the agent guesses

→ list_datasources()

← US1, US2, staging, EU, AUS, CA

actual production: US2 · EU · AUS · CA, but nothing in the response says so

“US1 sounds like the primary, so that must be prod.” It's the dev datasource.

→ query(datasource: "US1", …) // dev

Wrong data

Returns a list of auth errors from dev, from one datasource instead of four. It looks like an answer, but it's the wrong one.

Path B · the agent stops short

→ list_datasources()

← US1, US2, staging, EU, AUS, CA

“Nothing here is named prod or production…”

Dead end

“Sorry, I don't currently have access to production data.” Production was right there, under four names the agent had no way to recognize.

Path C · the agent checks first

→ get_tool_instructions()

← Prod = US2, EU, AUS, CA

your team's mapping, in context before any other call

“Production is four datasources, so query all of them.”

→ query(US2 · EU · AUS · CA)

Right data

Auth errors from all four production datasources, exactly what was asked for, on the first try.

Same prompt, same tools, three endings. The only difference in Path C is one piece of written-down team knowledge. Swap Grafana for Jira, Confluence, or Salesforce and the shape is the same.

03 · Why this happens

The context window is missing one block

Follow the messages. The prompt lands in the agent's context. The datasource list lands in the agent's context. But the one fact that makes the task doable, which datasources are production, lives only in your team's heads. It never enters the context window, so the agent has no way to know it.

Every fact the agent has arrives as a block in its context window. The prod mapping never arrives.

04 · The solution

Two segments, both written by your team

The Instruction Tool is two plain-text fields your team fills in: the Tool Description and the Instructions. No dropdowns, no fill-in-the-blanks: you write exactly what your agents should know, in your own words. The Tool Description tells the agent to call this tool before touching anything else in the gateway or deployment. The Instructions carry the rules and conventions the agent needs to use those tools well.

This setup means that whenever the agent decides it needs the gateway, it always has the context to use it properly. And when it doesn't need the gateway, the Instructions are never sent, saving valuable space in the context window. The information arrives exactly when it's useful.

Segment 1 · Tool Description · read in the catalog your team writes this

get_tool_instructions

EX:Call this before any other Grafana tool in this gateway. Returns our SRE team's conventions: which of the six datasources are production, how environments are tagged, and how we scope auth-error queries.

// always in the agent's tool list · a few dozen tokens

called → returns

Segment 2 · Instructions · sent only when called your team writes this

EX:# Grafana conventions
Production datasources → US2, EU, AUS, CA
Dev → US1 · Staging → staging

# Query all four prod datasources for any "prod" request

Where your team writes it

Create Gateway / Create Deployment → Configure → Instructions

Edit Gateway / Edit Deployment → Configure → Instructions

Gateways and Deployments each have their own flow, but the Instruction fields work identically in both: write them when you create, refine them any time you edit.

05 · How it works

Same scene, with the missing block filled in

Same user, same prompt, same gateway. But now the agent's first call fetches the instructions, so the prod mapping is in its context before it touches any other tool.

The instructions arrive at step 3, before any other tool call, so steps 4 through 6 use the right datasources.

06 · Use cases

Where teams use it

The Instruction Tool is useful anywhere your team knows things about a tool that its schema can't say.

Confluence

Navigating Confluence spaces

A little orientation goes a long way. Which spaces are authoritative, and which are archived? What organizational logic should the agent navigate by? A short map saves thousands of tokens of searching.

Jira

Writing Jira tickets

What belongs in a ticket, and what doesn't? Should the agent prescribe a specific fix, or describe the problem clearly and leave the solution to your engineers?

Slack

Navigating Slack

Which channels own which topics? Who should be looped in, and when? Where is a buttoned-up tone right, and where does casual land better?

GitHub

How to write GitHub PRs

Do PRs need a Jira ticket attached? Who should be tagged as a reviewer? Which checks should pass before a PR is opened for review?

Salesforce

Working with your Salesforce

Which objects and custom fields matter in your org? What do your opportunity stages really mean? Which records are open to the agent, and which should it treat as read-only?

Cross-app

Tool call sequencing across apps

Should the Jira ticket be created before the PR so the PR can reference it? Should the ticket be updated once the PR is up? Sequencing rules like these live in your team's habits; the Instruction Tool writes them down.